Back to Contents        Previous        Next



3. Handles

In the Wimp environment there is a frequent need to store detailed information in blocks of memory and subsequently to be able to access these blocks quickly and conveniently. For instance, definitions of windows, icons, menus, etc. all need to be stored in memory blocks and access to the blocks is necessary for displaying these items etc.

The most common way of managing this is to store the starting address of a particular memory block in an integer variable and to give that variable a meaningful name i.e. a name related to what is stored in the memory block. Thereafter, we can simply refer to this variable in order to access the memory block. For example, if the definition of the iconbar menu is stored in a memory block whose start address is assigned to the variable iconbarmenu%, then we can simply refer to iconbarmenu% whenever we need to do something with the iconbar menu.

Conventionally, the Wimp calls such identifiers “handles”. Thus, in our above example, iconbarmenu% holds the handle of the iconbar menu definition - or, for all practical programming purposes, iconbarmenu% is the handle of the iconbar menu.

The Wimp uses the same concept for many other items. For example, to use an outline font at a certain size you need a ‘font handle’ - which tells the Wimp where to look when it needs the detailed font information. Similarly, when you open a file, an access ‘channel’ is supplied and it is common to call this the ‘file handle’.

Just in case you are starting to get worried that you will need to get involved in a lot of memory details, please rest assured that the whole point of Dr Wimp is to hide all that from you.

You will also be relieved to know that the Wimp allocates memory blocks automatically and that Dr Wimp wimp-functions are specifically designed so that you can choose the handle names yourself and need know nothing about the actual memory locations - nor what they hold.

For instance, the wimp-function to define a simple menu is DEF FNwimp_createmenu(), whose parameters allow you to specify the menu item (and title) text. This wimp-function constructs the menu definition for you behind the scenes, asks the Wimp for a memory block to store it, and then returns the menu handle to you (i.e. returns the start address of the memory block which the Wimp automatically allocated). Typically, you would assign this returned handle directly to a meaningfully named integer variable, with a call similar to:

iconbarmenu%=FNwimp_createmenu()

and you don’t need to know what the actual memory address is, nor what it contains.


Similarly, a window called “save” held in a Templates file can be loaded into your program using FNwimp_loadwindow() - which, again, returns a handle for the loaded window. You might well assign this returned handle to an integer variable called save%. Thereafter, you can simply use save% whenever a reference to the save window is needed.


You will find that most wimp- and user-functions involve a handle to a window, icon, menu, etc. - so you will need to use handles very frequently.



To drive the message home, here is a typical practical sequence:

find% = FNwimp_loadwindow(“Templates”,“find”,0)
PROCwimp_openwindow(find%,1,-1)


The first line loads into our program the definition of a window called “find” which is held in a templates file called “Templates”. We can assume that it is a window for entering something to find. So, here, we have chosen find% for the handle name and the function duly returns the start address of the memory block (allocated automatically by the Wimp) into find%.

The second line gives an example of how we use the handle. Here, a wimp-function is being called that opens a window. Passed to it in the first parameter is the window handle from the first line - telling it which window to open. The details of the memory block are invisible to us and we need know nothing more about it - the handle is all we need. (The meaning of the other parameters need not concern us here and will be covered later in this Manual.)

Don’t forget - it is up to you to choose the name for a handle. It could be anything, eg:

coffee% = FNwimp_loadwindow(“Templates”,“find”,0)

Or changed later on, eg:

find% = FNwimp_loadwindow(“Templates”,“find”,0)
coffee% = find%

i.e. a handle is an ordinary Basic integer variable.









Top of page        Back to Contents        Previous        Next